1 /************************************************************
2 * Copyright *
3 * Portions of this software are Copyright (c) 1993 - 2002, *
4 * Chad Z. Hower (Kudzu) and the Indy Pit Crew *
5 * - http://www.nevrona.com/Indy/ *
6 ************************************************************/
7 package org.indy.io;
8
9 import java.util.Map;
10
11 /***
12 * An <code>IOHandler</code> wraps an underlying communications mechanism
13 * and provides access to its IO facilities and some convinivence methods.
14 *
15 * It is assumed that concrete implementations will implement some sort
16 * of buffering mechanism, at least for read operations to incraese efficiency.
17 *
18 * Implementors may prefer instead to sub-class {@link AbstractIOHandler}
19 * which provides a number of convinience no-ops and skeletal method implementations.
20 *
21 */
22 public interface IOHandler {
23 /***
24 * Determines whether or not this <code>IOHandler</code> is connected.
25 *
26 * @return <code>true</code> if connected <code>false</code> otherwise
27 */
28 boolean isConnected();
29
30 /***
31 * Invoked after a server-side accept() operation
32 */
33 void afterAccept();
34
35 /***
36 * Closes this <code>IOHandler</code>
37 *
38 * Should generate an {@link IOHandlerListener#onDisconnect(IOHandler)} event.
39 *
40 */
41 void close();
42
43 /***
44 * Reads a single byte of data from this <code>IOHandler</code>'s input
45 * @return A byte of data from this <code>IOHandler</code>
46 * @throws IndyIOException if an IOError occurs
47 */
48 int read() throws IndyIOException;
49
50 /***
51 * Reads a single byte of data from this <code>IOHandler</code>'s input
52 *
53 * @param timeout The timeout to use for this read operation
54 * @return A byte of data from this <code>IOHandler</code>
55 * @throws IndyIOException if an IOError occurs
56 */
57 int read(int timeout) throws IndyIOException;
58
59 /***
60 * Clears the input buffer of this <code>IOHandler</code>
61 */
62 void clearBuffer();
63
64 /***
65 * DOCUMENT ME!
66 *
67 * @return DOCUMENT ME!
68 *
69 * @throws IndyIOException DOCUMENT ME!
70 */
71 /***
72 * Retreives the contents of the <code>IOHandler</code>'s input
73 * that can be read without blocking.
74 *
75 * @return The data available without blocking
76 * @throws IndyIOException If an IOError occurs.
77 */
78 byte[] currentReadBuffer() throws IndyIOException;
79
80 /***
81 * Reads a line of text from the <code>IOHandler</code>'s input
82 * using the properties for read timeout and maxiumum linelength
83 *
84 * @return A line of text from the <code>IOHandler</code>
85 * @throws IndyIOException if an IO error occurs
86 * @see getReadTimeOut()
87 * @see setReadTimeOut(int,int)
88 * @see getMaximumLineLength()
89 * @see setMaximumLineLength(int)
90 */
91 String readLine() throws IndyIOException;
92
93 /***
94 * Reads a line of text from the <code>IOHandler</code>'s input.
95 *
96 * @param timeout the timeout to use for this operation
97 * @param maxLine the maxium line length to accepy
98 * @return A line of text from the <code>IOHandler</code>
99 * @throws IndyIOException if an IO error occurs.
100 */
101 String readLine(int timeout, int maxLine) throws IndyIOException;
102
103 /***
104 * Reads a line of text from the <code>IOHandler</code> using
105 * If <code>encoding</code> is <code>null</code> the default
106 * character encoding for the platform will be used.
107 *
108 * @param timeout the timeout to use for this operation
109 * @param maxLine the maximum line length to accept
110 * @param encoding the character encoding to use.
111 * @return A line of text
112 * @throws IndyIOException
113 */
114 String readLine(int timeout, int maxLine, String encoding)
115 throws IndyIOException;
116
117 /***
118 * Connects this <code>IOHandler</code> to a remote implementation.
119 * The contents of map depend on the implementation in question,
120 * so a socket may have values for host, port etc.
121 *
122 * Concrete implementations may also find it useful to provide
123 * a connect method with implementation specific parameters.
124 *
125 * Concrete implementations should consider allowing map populations that are all
126 * Strings, so as to allow easy storage of connection parameters using java.util.Properties
127 *
128 * Successful connection should generate an {@link IOHandlerListener#onConnect(IOHandler)} event.
129 *
130 * @param parameters A <code>java.util.Map</code> containing implementation specific connection parameters.
131 * @param timeout The timeout to use for connecting
132 * @throws IndyIOException If an IO error occurs
133 * @throws ConnectException If a connection error occurs
134 * @throws ConnectTimedOutException If connection times out.
135 */
136 void connectClient(Map parameters, int timeout) throws IndyIOException,
137 ConnectException,
138 ConnectTimedOutException;
139
140 /***
141 * I'm not actually sure what this is here for. More news as it comes, kids.
142 */
143 void open();
144
145 /***
146 * Flushes the output of this <code>IOHandler</code>.
147 *
148 * @throws IndyIOException if an IO error occurs
149 */
150 public void flush() throws IndyIOException;
151
152 /***
153 * Writes some bytes to this <code>IOHandler</code>'s output.
154 *
155 * @param b The bytes to write
156 * @param off The offset at which to start writing
157 * @param len The number of bytes to write
158 * @throws IndyIOException if an IO error occurs.
159 */
160 void write(byte[] b, int off, int len) throws IndyIOException;
161
162 /***
163 * Writes some bytes to this <code>IOHandler</code>'s output.
164 *
165 * @param b The bytes to write
166 * @throws IndyIOException if an IO error occurs.
167 */
168 void write(byte[] b) throws IndyIOException;
169
170 /***
171 * Writes a single byte to this <code>IOHandler</code>'s output
172 *
173 * @param b The byte to be written
174 * @throws IndyIOException if an IO error occurs.
175 */
176 void write(int b) throws IndyIOException;
177
178 /***
179 * Reads some bytes from this <code>IOHandler</code>
180 *
181 * @param b A buffer to read the bytes into
182 * @return The number of bytes read
183 * @throws IndyIOException if an IO error occurs
184 */
185 int read(byte[] b) throws IndyIOException;
186
187 /***
188 *Reads up to <code>len</code> bytes from this <code>IOHandler</code>
189 *
190 * @param b The buffer to read the bytes into
191 * @param len The number opf bytes to be read
192 * @return The actual number of bytes read
193 * @throws IndyIOException if an IO error occurs.
194 */
195 int read(byte[] b, int len) throws IndyIOException;
196
197 /***
198 * Reads up to <code>len</code> bytes from this <code>IOHandler</code> into
199 * <code>b</code> starting at <code>off</code>
200 *
201 * @param b The buffer to read into
202 * @param off The buffer offset to start filling at
203 * @param len The number of bytes to read
204 * @return The actual number of bytes read
205 * @throws IndyIOException if an IO error occurs.
206 */
207 int read(byte[] b, int off, int len) throws IndyIOException;
208
209 /***
210 * Reads up to <code>len</code> bytes from this <code>IOHandler</code> into
211 * <code>b</code> starting at <code>off</code> waiting for up to <code>timeout</code>
212 * for data.
213 *
214 * @param b The buffer to read into
215 * @param off The buffer offset to start filling at
216 * @param len The number of bytes to read
217 * @param timeout The timeout to use for this operation
218 * @return The actual number of bytes read
219 * @throws IndyIOException if an IO error occurs.
220 */
221 int read(byte[] b, int off, int len, int timeout) throws IndyIOException;
222
223 /***
224 * Gets the number of bytes that can be read from this <code>IOHandler</code>
225 * without blocking
226 *
227 * @return the number of bytes that can be read without blocking
228 * @throws IndyIOException if an IO error occurs
229 */
230 int available() throws IndyIOException;
231
232 /***
233 * Get the timeout to use for read operations on this <code>IOHandler</code>
234 * @return the time out to use for read operations by default
235 * @throws IndyIOException If the IOHandler is connected and an IOError occurs
236 */
237 int getReadTimeOut() throws IndyIOException;
238
239 /***
240 * Sets the timeout to use for read operations on this <code>IOHandler</code>
241
242 * @param newTimeout The new timeout to use
243 * @throws IndyIOException If the IOHandler is connected and an IOError occurs
244 */
245 void setReadTimeOut(int newTimeout) throws IndyIOException;
246
247 /***
248 * Gets the maximum line length to be used for read line operations
249 *
250 * @return The maximum line length accepted by this <code>IOHandler</code
251 */
252 int getMaximumLineLength();
253
254 /***
255 * Sets the maximum line length to be acceped by this <code>IOHandler</code>
256 *
257 * @param newMaximumLineLength The new maximum line length
258 * @throws IllegalArgumentException if <code>newMaximumLineLength</code> is < 0
259 */
260 void setMaximumLineLength(int newMaximumLineLength);
261
262 /***
263 * Add a {@link IOHandlerListener} to receive events from this <code>IOHandler</code>
264 *
265 * @param l The <code>IOHandlerListener</code>
266 */
267 void addIOHandlerListener(IOHandlerListener l);
268
269 /***
270 * Remove a {@link IOHandlerListener} from this <code>IOHandler</code>'s
271 * listener listl
272 *
273 * @param l The <code>IOHandlerListener</code>
274 */
275 void removeIOHandlerListener(IOHandlerListener l);
276 }
This page was automatically generated by Maven